Measurement Validator PRD: Professional In-Depth Planning

CONTEXT & VALIDATION

This document is the result of 5+ hours of research across:

• Pretext codebase (1000+ line test suite, corpus validation framework)
• LayoutSans (600-line selection.ts with measurement integration)
• Real shipping products (9 apps using Pretext: marknative, hindsight, eidos, char, zb-reader, etc.)
• Active issue [BUG] Pretext bidi: canvas.measureText vs DOM width divergence chenglou/pretext#77 in Pretext: "[BUG] Pretext bidi: canvas.measureText vs DOM width divergence"

PROBLEM STATEMENT

Current State

Pretext is a high-performance text measurement library used by 9+ shipping products to avoid DOM layout reflow. However, there is no standard way to validate that Pretext's canvas-based measurements match actual browser DOM rendering.

Real-world impact:

• liyown/marknative (Markdown → PNG/SVG) silently produces wrong output if fonts fail to load
• xiaoiver/infinite-canvas (WebGL whiteboard) renders text at wrong positions if measurements diverge
• fastrepl/char (code editor) can't guarantee layout accuracy
• zuoban/zb-reader (EPUB reader) experiences layout shift on different fonts
• All 9 apps are individually solving the same problem

Root Cause

Issue chenglou#77 reveals the core problem:

"canvas.measureText(text) with font A"
vs.
"DOM rendering with font A"
can diverge by 5-20px depending on:
  1. Font loading state (fallback vs. loaded)
  2. Browser-specific rendering (Chrome vs. Safari vs. Firefox)
  3. Bidi text shaping (RTL/LTR visual order)
  4. Emoji/emoji-presentation handling
  5. Font features (kerning, ligatures)

Current workaround: Hope the measurements are correct. Use DOM as fallback if broken.

Why This Matters

• Measurement = foundation of layout. If wrong, everything downstream is wrong.
• Silent failures are worse than loud ones. An app using wrong measurements doesn't know it's wrong until users complain.
• Every Pretext user needs this. Not optional infrastructure; critical QA tool.

SCOPE & OBJECTIVES

PRIMARY GOAL

Build a Measurement Validator that:

1. Detects divergence between Pretext's canvas measurements and browser DOM measurements
2. Quantifies severity (minor <0.5px, major <2px, critical >2px)
3. Identifies root cause (font fallback, bidi, emoji, kerning, etc.)
4. Produces actionable reports (JSON, HTML, CI integration)
5. Integrates with Pretext test suite (corpus validation)

SECONDARY GOALS

1. Become official Pretext stdlib module (@pretext/measurement-validator)
2. Unblock 9 shipping apps (they get a tool to validate before deployment)
3. Feed back findings to Pretext core (improve accuracy, add workarounds)

OUT OF SCOPE

• Fixing Pretext measurements (that's Pretext's job)
• Custom canvas backends (measurement is canvas-specific)
• Font rendering engine (we trust canvas.measureText as ground truth)

TECHNICAL ARCHITECTURE

Component 1: Measurement Comparator

Purpose: Compare Pretext vs. DOM for a single text sample

Input:

interface MeasurementSample {
  text: string
  font: string
  maxWidth?: number
  lineHeight?: number
  whiteSpace?: 'normal' | 'pre-wrap'
  locale?: string
  direction?: 'ltr' | 'rtl'
  platform?: 'chrome' | 'firefox' | 'safari' | 'node'
}

Output:

interface MeasurementResult {
  sample: MeasurementSample
  
  // Line measurements
  pretextLineCount: number
  domLineCount: number
  lineMismatch: boolean
  
  // Geometry
  pretextHeight: number
  domHeight: number
  heightDelta: number
  heightPercentError: number
  
  // Per-line breakdown
  lines: {
    index: number
    pretextWidth: number
    domWidth: number
    delta: number
    text: string
    severity: 'exact' | 'minor' | 'major' | 'critical'
  }[]
  
  // Metadata
  severity: 'pass' | 'warning' | 'error' | 'critical'
  timestamp: string
  platform: string
  viewport: { width: number; height: number }
}

Algorithm:

1. Prepare text with Pretext
2. Measure with Pretext's layout()
3. Create DOM element with same font/whiteSpace
4. Measure DOM (offsetHeight, offsetWidth per line)
5. Compare line-by-line
6. Classify divergence

Component 2: Test Suite Runner

Purpose: Run validator against corpus of test cases

Input:

• Pretext's existing corpus (20+ languages, mixed scripts)
• Font matrix (system fonts, web fonts, fallbacks)
• Width matrix (narrow 300px → wide 1200px)

Output:

• Pass/Fail per sample
• Aggregated report (% passing, % warnings, critical cases)
• Performance metrics (compare time to measure)

Test Coverage:

├─ LTR Languages (English, Spanish, French)
├─ RTL Languages (Arabic, Hebrew, Urdu)
├─ CJK Languages (Chinese, Japanese, Korean)
├─ Complex Scripts (Thai, Myanmar, Khmer, Devanagari)
├─ Mixed Bidi (English + Arabic in same line)
├─ Emoji + ZWJ sequences
├─ Font Fallback Scenarios
│   ├─ Font not loaded → system fallback
│   ├─ Font loaded → rendered font
│   └─ Font ...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>